---
title: 画像
description: Astroでの画像の取り扱いを学びます
i18nReady: true
---
import Since from '~/components/Since.astro';

Astroは、プロジェクト内に保存されている画像やリモート上にリンクされている画像、CMSやCDNに保存されている画像をサイト上で表示するために様々な手段を提供しています。

:::note[アセットの活用 (実験的)]
実験的なアセットサポートが`astro@2.1.0`に追加されました。アセットサポートを有効にした場合、追加情報については [アセット (実験的) ガイド](/ja/guides/images/) を参照してください。

**以下のアドバイスの中には、アセットのフラグを有効にした場合に互換性がなくなるものもあります。**
:::


### `.astro`ファイル内

astroでは`<img>`要素を使って画像を表示でき、HTML画像属性をすべてサポートしています。

`src` 属性は必須で、その書式は画像の保存場所や、アセットの実験的なサポートを有効にしているかどうかによって異なります：

```astro title="src/pages/index.astro"
---
import rocket from '../images/rocket.svg';
---
<!-- 他サーバー上のリモート画像 -->
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro">

<!-- public/assets/stars.png に保存されているローカル画像 -->
<img src="/assets/stars.png" alt="A starry night sky.">

<!-- src/images/rocket.svg に保存されているローカル画像 -->
<img src={rocket} alt="A rocketship in space."/>
```

### Markdownファイル内

`.md`ファイル内では標準的な`![]()`構文や`<img>`タグを記載することで`public/`フォルダや、他サーバー上にあるリモート画像を表示できます。

もし`public/`に画像を保存できない場合、[アセットの実験的なサポート](/ja/guides/images/)を有効にするか、インポートされたコンポーネントをMarkdownのような構文と組み合わせて使える`.mdx`ファイルフォーマットを利用することをお勧めします。AstroにMDXのサポートを追加するには[MDX インテグレーション](/ja/guides/integrations-guide/mdx/)を利用します。

```md
<!-- src/pages/post-1.md -->

# Markdownページ

<!-- public/assets/stars.png に保存されたローカル画像 -->
![A starry night sky.](/assets/stars.png)
<img src="/assets/stars.png" alt="A starry night sky.">

<!-- 他サーバー上にあるリモート画像 -->
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro">
```

### MDXファイル内

`.mdx`ファイル内では標準的なMarkdown文法`![]()`やJSXの`<img />`タグを使って`public/`フォルダーやリモートサーバーの画像を表示できます。

加えて、Astroコンポーネントのようにプロジェクトの`src/`ディレクトリに保存されている画像をインポートして利用できます。

```mdx title="src/pages/post-1.mdx"

import rocket from '../images/rocket.svg';

# MDXページ

// src/images/rocket.svgに保存されたローカル画像
<img src={rocket} alt="A rocketship in space."/>

// public/assets/stars.pngに保存されたローカル画像
![A starry night sky.](/assets/stars.png)
<img src="/assets/stars.png" alt="A starry night sky." />

// 他サーバー上にあるリモート画像
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro" />
```

### UIフレームワークコンポーネント内

[UIフレームコンポーネント](/ja/core-concepts/framework-components/)(ReactやSvelteなど)に画像を追加する場合、そのコンポーネントのフレームワークに沿った画像の構文を利用します。

## 画像の保存場所

### `src/`

`src`に保存された画像は、コンポーネント(`.astro`や`.mdx`、そして他のUIフレームワーク)から利用できますが、Markdownファイルからは利用できません。

Markdownファイルを利用する必要がある場合、[`public/`へ配置する](#public)か[CMSやCDN上の画像を利用](#cmsやcdn上の画像利用)することをお勧めします。

画像を**相対ファイルパス**または[importエイリアス](/ja/guides/aliases/)を利用してコンポーネントファイル内でインポートし、画像の`src`属性として利用できます。


```astro
---
// src/pages/index.astro

// `src/images/`内の画像へアクセスします。
import logo from '../images/logo.png';
---
<img src={logo} width="40" alt="Astro" />
```

### `public/`

`public/`に保存された画像はコンポーネント(`.astro`や`.mdx`、そして他のUIフレームワーク)とMarkdownファイルからも利用できます。

しかし、`/public`ディレクトリにあるファイルは処理されずにそのまま提供、コピーされます。Markdownファイル以外で画像を利用する場合はAstroが画像を変換・最適化・バンドルできるように、可能な限りローカル画像は`src`に保存するのをお勧めします。

`src`属性は**publicフォルダからの相対パス**です。Markdownでは`![]()`の表記を利用できます。

```astro title="src/pages/index.astro"
---
// `public/images/`内の画像へアクセスします。
---
<img src="/images/logo.png" />
```

### `src/assets/` (実験的)

`/assets/` フォルダの実験的な使用を有効にするには、[アセット(実験的)](/ja/guides/images/)ガイドを参照してください。

その場合、既存の画像を更新し、現在のAstro画像インテグレーションを削除する必要があります。また、Astroの新機能の一部を利用するためには、さらに手動での変更が必要になります。

## Astro画像インテグレーション

Astro公式の画像のインテグレーションは、最適化された画像をレンダリングするためのAstroコンポーネント`<Image />`と`<Picture />`を提供しています。これらのコンポーネントは全ての静的サイトと、[一部のサーバーサイドレンダリングのデプロイホスト](/ja/guides/integrations-guide/image/#installation)をサポートしています。

[`@astrojs/image`のインストール](/ja/guides/integrations-guide/image/#installation)で、`.astro`と`.mdx`などのAstroコンポーネントを利用できるファイル内でこの2つのコンポーネントを利用できます。

:::note[アセットの互換性がない]
アセットの実験的なサポートを有効にしている場合は、公式インテグレーションをアンインストールする必要があります。詳細については、[アセット (実験的) ガイド](/ja/guides/images/) を参照してください。
:::

### `<Image />`

Astroの[`<Image />`コンポーネント](/ja/guides/integrations-guide/image/#image-)は1つの画像を最適化し、幅・高さ・アスペクト比を指定できます。また特定の出力フォーマットに画像を変換できます。

このコンポーネントはディスプレイ間で一貫したサイズを維持したい画像や、画質を厳密にコントロールしたいもの(ロゴなど)に有効です。

レスポンシブ画像の場合やアートディレクションの場合は、代わりに`<Picture />`コンポーネントを利用します。

#### リモート画像

(必須属性:  [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt)・[`format`](/ja/guides/integrations-guide/image/#format)・サイズ)

`<Image />`コンポーネントの`src`属性に完全なURLを渡し、`alt`の値を含めます。

`<Image />`コンポーネントはリモート画像のオリジナルのファイルフォーマットを検知できないため、リモート画像を変換するために出力する`format`(pngやavifなど)を指定する必要があります。

`<Image />`コンポーネントはリモート画像のサイズを認識しないので、コンテンツレイアウトのシフトを回避するために[`width`](/ja/guides/integrations-guide/image/#width)と[`height`](/ja/guides/integrations-guide/image/#height)、またはどちらか1つのサイズと[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio)を指定する必要があります。

[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションです。

#### `src/`のローカル画像

(必須属性:  [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt))

フロントマターで画像をインポートして、`<Image />`コンポーネントの`src`属性へ直接渡します。

`alt`は必須ですが[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションで、指定が無ければ画像ファイルのプロパティがデフォルト値として設定されます。

#### `public/`のローカル画像

(必須属性: [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt)・[`format`](/ja/guides/integrations-guide/image/#format)・サイズ)

コンポーネントの`src`属性に公開フォルダからの相対パスを渡し、`alt`に値を含めます。

これはリモート画像として扱われ、[`width`](/ja/guides/integrations-guide/image/#width)と[`height`](/ja/guides/integrations-guide/image/#height)の両方の属性か、またはどちらか1つのサイズと[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio)属性が必須です。

画像を変換するための`format`属性値が必要です。(pngやavifなど)

[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションです。

元画像は`public/`にある他のファイルと同じくビルドフォルダーにそのままコピーされ、Astroの画像インテグレーションは最適化された画像を返します。

#### 例

```astro
---
// src/pages/index.astro
import { Image } from '@astrojs/image/components';
import localImage from "../assets/logo.png";
const remoteImage = "https://picsum.photos/id/957/300/200.jpg";
const localAlt = "The Astro Logo";
const remoteAlt = "A low-angle view of a forest during the daytime";
---

<!-- 元画像の幅、高さ、フォーマットを維持したままの最適化されたローカル画像 -->
<Image src={localImage} alt={localAlt} />

<!-- 元画像のアスペクト比に合わせて高さが再計算されます-->
<Image src={localImage} width={300} alt={localAlt} />

<!-- リモート画像では、サイズとフォーマットの指定が必要です -->
<Image src={remoteImage} width={300} aspectRatio="1:1" format="png" alt={remoteAlt} />

<!-- 特定の幅と高さで切り取りをします -->
<Image src={localImage} width={300} height={600} alt={localAlt}/>
<Image src={remoteImage} width={544} height={184} format="png" alt={remoteAlt}/>

<!-- 特定のアスペクト比で切り取り、avifフォーマットに変換されます -->
<Image src={localImage} aspectRatio="16:9" format="avif" alt={localAlt}/>
<Image src={remoteImage} height={200} aspectRatio="16:9" format="avif" alt={remoteAlt}/>

<!-- ローカル画像のインポート文はそのままインライン化できます -->
<Image src={import('../assets/logo.png')} alt={localAlt}/>

<!-- 画像が`/public`フォルダーにある場合、`/public`からの相対パスを利用します -->
<Image src="/penguin.jpg" width="300" aspectRatio={1} format="png" alt="A happy penguin"/>
```

### `<Picture /> `

Astroの[`<Picture />`コンポーネント](/ja/guides/integrations-guide/image/#picture-)は複数の画像サイズ・フォーマット・レイアウトなど、サイト上でレスポンシブな画像を提供するために利用できます。

画面サイズや帯域幅に基づいて、画像に最適なサイズ、解像度、ファイルタイプを利用ユーザーのブラウザに任せることができます。また、メディアクエリに基づいてブラウザに従わせるルールを指定できます。

このコンポーネントは、ユーザーが様々な画面サイズで見る画像を最適化するためや、アートディレクションに最適です。

:::tip
[レスポンシブ画像とアートディレクション](https://developer.mozilla.org/ja/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#%E3%82%A2%E3%83%BC%E3%83%88%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3)の詳細はMDNのガイドを参照してください。
:::

#### リモート画像

(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1)・[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio-1))

完全なURLを`<Picture />`コンポーネントの`src`属性へ渡します。

またビルド時に正しい高さを計算できるようにリモート画像は`aspectRatio`も必要になります。

画像の幅と画面サイズに関する指示をコンポーネントに与える必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。

[`formats`](/ja/guides/integrations-guide/image/#formats)は必須ではありませんが、リモート画像の元のフォーマットが不明となりデフォルト値は含まれません。何も指定が無ければ、`webp`と`avif`だけが含まれます。

#### ローカル画像

(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1))

フロントマターで画像をインポートして、`<Picture />`コンポーネントの`src`属性へ直接渡します。

画像の幅と画像のガイダンスをコンポーネントへ渡す必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。

`<Picture />`コンポーネントの[`formats`](/ja/guides/integrations-guide/image/#formats)に指定がなければ、デフォルト値は元の画像のフォーマットに加えて`avif`と`webp`が含まれます。

#### `public/`の画像

(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1)・[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio-1))

コンポーネントの`src`属性にはpublicフォルダからの相対パスを渡し、`alt`の値を必要とします。

画像はリモート画像として扱われるため、ビルド時に正しい高さを計算できるように`aspectRatio`の指定が必要です。

画像の幅と画面サイズに関する指示をコンポーネントに与える必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。

[`formats`](/ja/guides/integrations-guide/image/#formats)は必須ではありませんが、`public/`フォルダにある画像の元のフォーマットが不明となりデフォルト値は含まれません。何も指定が無ければ、`webp`と`avif`だけが含まれます。

元の画像は`public/`にある他のファイルと同じくビルドフォルダーにそのままコピーされ、Astroの画像インテグレーションは最適化された画像を返します。

#### 例

```astro
---
import { Picture } from '@astrojs/image/components';
import localImage from '../assets/logo.png';
const remoteImage = 'https://docs.astro.build/assets/full-logo-light.png';
---

<!--複数のサイズとフォーマットが指定されたローカル画像 -->
<Picture src={localImage} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" formats={['avif', 'jpeg', 'png', 'webp']} alt="The Astro logo" />

<!-- リモート画像(アスペクト比は必須です)-->
<Picture src={remoteImage} widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="The Google logo" />

<!-- /publicにある画像はリモート画像として動作します -->
<Picture src="/logo.png" widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="The Google logo" />

<!-- インラインインポートもサポートされます -->
<Picture src={import("../assets/logo.png")} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="The Astro logo" />

```

### MDXでの利用

`.mdx`ファイル内では、インポートとエクスポートを通して`<Image />`と`<Picture />`が画像の`src`を受け取ることができます。

```mdx
// src/pages/index.mdx

import { Image, Picture } from '@astrojs/image/components';
import rocket from '../assets/rocket.png';
export const logo = 'https://docs.astro.build/assets/full-logo-light.png';

<Image src={import('../assets/galaxy.png')} alt="Outer space."/>
<Image src={rocket} width={300} alt="Spaceship approaching the moon."/>
<Picture src={rocket} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="A rocket blasting off." />
<Picture src={logo} widths={[200, 400, 800]} aspectRatio={16/9} sizes="(max-width: 800px) 100vw, 800px" alt="The full Astro logo." />
```

### デフォルト値を設定する

現在、`<Image />`と`<Picture />`コンポーネントにデフォルト値を指定する方法はありません。必須属性はそれぞれのコンポーネントに設定する必要があります。

代わりの方法として、再利用できるよう他のAstroコンポーネントでこれらのコンポーネントをラッピングできます。例えば、以下のようにブログ記事画像をコンポーネントとして作成できます。

```astro title="src/components/BlogPostImage.astro"
---
import { Picture } from '@astrojs/image/components';

const {src, ...attrs} = Astro.props;
---
<Picture src={src} widths={[400, 800, 1500]} sizes="(max-width: 767px) 100vw, 736px" {...attrs} />

<style>
  img, picture :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

### 画像インテグレーションで`<img>`を使う

公式の画像インテグレーションにより、画像のインポートはソース文字列ではなくオブジェクトを返すように変更されます。このオブジェクトは、インポートされたファイルから派生した以下のプロパティを持ちます。
```ts
{
  src: string;
  width: number;
  height: number;
  format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp';
}
```

画像インテグレーションがインストールされている場合は、`<img>`を使用する際にオブジェクトの`src`プロパティを参照してください。

```astro ".src"
---
import rocket from '../images/rocket.svg';
---
<img src={rocket.src} alt="A rocketship in space."/>
```

あるいは、インポートに`?url`を追加して、ソース文字列を返すように指示する。

```astro "?url"
---
import rocket from '../images/rocket.svg?url';
---
<img src={rocket} alt="A rocketship in space."/>
```

## CMSやCDN上の画像利用

CDNネットワーク上の画像をAstroで利用するには、画像の完全なURLを`<img>`タグやMarkdownの`src`属性として利用します。

代わりに、もしCDNがNode.js SDKを提供している場合はプロジェクトでSDKを利用できます。例えば、[CloudinaryのSDK](https://cloudinary.com/documentation/node_integration)は適切な`src`を利用して`<img>`タグを生成できます。

Astroの画像インテグレーションの[`<Image />`を用いた外部画像](#リモート画像)や[`<Picture />`](#リモート画像-1)コンポーネントを利用するには、リモート画像を扱うための適切なサイズとフォーマットを指定する必要があります。

## Altテキスト

画像が誰も同じように見えるわけではないため、画像を扱う上でアクセシビリティは特に重要になります。`alt`属性は画像に[Altテキストによる記述](https://www.w3.org/WAI/tutorials/images/)を与えます。

この属性は画像インテグレーションの`<Image />`と`<Picture />`コンポーネントには必須です。Altテキストが指定されていない場合これらのコンポーネントはエラーを投げます。

画像が単なる飾り(ページの理解に貢献しない画像)の場合、スクリーンリーダーが画像を無視するように`alt=""`を設定します。

## コミュニテーインテグレーション

公式の[`@astrojs/image`](/ja/guides/integrations-guide/image/)インテグレーションに加え、Astroプロジェクトで画像の最適化や処理を行うためのサードパーティー製の[コミュニティー画像インテグレーション](https://astro.build/integrations?search=images)がいくつかあります。
